# Oracle Application Server Portlet Developer Kit (PDK)
Migrating Applications to PDK-Java Release 9.0.4 and later

Last Updated: | February 7, 2007
Status: | Production
Version: | PDK Release 10.1.3.2.0

### Contents

1. Overview
2. Migration Options
3. Migrating from PDK-Java 9.0.2.x (v2) to PDK-Java 9.0.4 and later
4. Migrating from PDK-Java 9.0.2.x (v1) to PDK-Java 9.0.4 and later
5. Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.4 and later

# Overview

This document describes how to migrate applications built with earlier releases of PDK-Java to run on the latest version of the framework. This document assumes you have already followed the intructions in Installing the PDK-Java Framework to install or upgrade the PDK-Java framework in your target Oracle Application Server or OC4J Standalone installation.

Please review the Release Notes for a detailed description of the changes since these earlier releases.

# Migration Options

PDK-Java 9.0.2.x included two versions of the PDK-Java framework known as version 1 (v1) and version 2 (v2). Version 1 was provided for backward compatibility with the PDK-Java 3.0.9.x API, Servlet 2.0 API and the the JServ servlet container. Version 2 established a more object-oriented and extensible, J2EE-compatible API, which was extended further in the 9.0.4 release. The 9.0.4 release also built on the enterprise features provided by the 9.0.4 Application Server environment, and hence states Oracle Application Server 9.0.4 as its minimum supported application server version.

This means that there are effectively 3 migration paths to this latest version of PDK-Java. The options are:

1. Migrate from PDK-Java 9.0.2.x (v2) to PDK-Java 9.0.4 and later
2. Migrate from PDK-Java 9.0.2.x (v1) to PDK-Java 9.0.4 and later
3. Migrate from PDK-Java 3.0.9.x to PDK-Java 9.0.4 and later

Option 1 is the easiest because it does not require any changes to your existing web providers, since the PDK-Java 9.0.4 API is completely backward compatible with PDK-Java 9.0.2.x (v2).

Options 2 and 3 require a little more work, because your web providers need to be modified to use the new framework. For most web providers, the changes you need to make are relatively straightforward, involving modifying the import statements in your Java classes and changing the classes used for some method calls. Generally, all the methods that existed in version 1 of the framework are still there and their function has not changed but the class they are contained in may have changed. Even though option 2 requires a little extra work, once you have completed the conversion you will be able to take advantage of the features of the OC4J servlet container and the new features/functionality included in the 9.0.4 version of the framework.

The remainder of this document describes each of the migration options in detail.

## Migrating from PDK-Java 9.0.2.x (v2) to PDK-Java 9.0.4 and later

Because the PDK-Java 9.0.4 API is completely backward compatible with PDK-Java 9.0.2.x (v2), this should be the most straightforward of the migration paths. However, because PDK-Java 9.0.4 requires Oracle AS 9.0.4, the main task is to migrate enterprise applications from the older application server to the newer one.

If you have the original .ear file for the provider application you want to migrate, migration may be a simple matter of deploying the .ear file on your new Oracle Application Server middle tier. However, in some cases the original .ear file alone is not enough, as there are certain types of Provider that add extra meta data to their web applications after deployment. Examples of such providers are:

- Web Providers built through the Portal UI
- Customizable Providers configured with the default settings for FilePreferenceStore, where customization data is written under the WEB-INF directory of the provider itself.
- Providers customized by the user after deployment, e.g where edits have been made to .jsp files inline.

To get around this problem, PDK-Java provides the Transporter utility, which can be used to repackage a deployed application back into EAR file format, complete with any web app content and meta data that has been added or changed since deployment. To use it, enter the following command:

java -classpath $dest_oracle_home/portal/jlib/pdkjava.jar oracle.webdb.provider.v2.tools.Transporter $source_oracle_home/j2ee/$oc4j_instance/applications/$application_name $destination_ear_file

where:

- $dest_oracle_home is the root directory of the Oracle AS installation to which you want to migrate the application
- $source_oracle_home is the root directory of the Oracle AS installation containing the application to be migrated
- $application_name is the name of the application to be migrated
- $oc4j_instance is the name of the target OC4J instance with PDK-Java installed that the application should be deployed into (e.g. OC4J_Portal).
- $destination_ear_file is the full path to your EAR file on the filesystem

This should result in a new EAR file being written to $destination_ear_file, complete with any extra data added to the application since deployment.

For example:

java -classpath D:\as904\portal\jlib\pdkjava.jar oracle.webdb.provider.v2.tools.Transporter D:\ora9ias\j2ee\OC4J_Portal\applications\jpdk D:\jpdk-rezipped.ear

To complete the migration, you simply need to take the following steps

1. If any of the providers use DBPreferenceStore, add appropriate entries to $dest_oracle_home/j2ee/$oc4j_instance/config/data_sources.xml, so that the same data sources used by the preference store are available with the same JNDI path to the migrated providers.
2. Deploy this new .ear file, and test it through the test page URL.
3. For all Portals associated with the migrated providers, navigate to each provider on the Providers tab of the Navigator screen and use the Edit Registration link to edit the registration to use the new provider URL (the same as the default test page URL)

## Migrating from PDK-Java 9.0.2.x (v1) to PDK-Java 9.0.4 and later

Migrating from PDK-Java 9.0.x (v1) to PDK-Java 9.0.x (v2) requires that you follow the steps described in the section Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.x (v2)

## Migrating from PDK-Java 3.0.9.x to PDK-Java 9.0.4 and later

This section outlines the changes you will need to make to an existing (PDK-Java 3.0.9) provider.

### Update Java classes, Servlets and JSPs

For this section you will most likely need to refer to the JavaDoc for the new framework. The JavaDoc is installed with the PDK-Java sample providers and should be accessible at the following URL: http://<host>:<port>/jpdk/apidoc where <host> is the name of the computer on which Oracle Application Server 9.0.x is installed and <port> is the port number the HTTP listener has been configured to listen on. The PDK-Java (v2) samples are installed automatically when you install OracleAS Portal.

> 1. change import statements in Java classes and JSPs to reflect new package organization. The package hierarchy is now more structured with packages organized based on functional areas such as rendering, security, personalization etc.
> 2. replace references to oracle.portal.provider.v1.Provider with oracle.portal.provider.v2.ProviderInstance or oracle.portal.provider.v2.ProviderDefinition depending on the method being called. Review the JavaDoc to determine which of these classes contains the specific method you are calling.
> 3. replace references to oracle.portal.provider.v1.Portlet with oracle.portal.provider.v2.PortletInstance or oracle.portal.provider.v2.PortletDefinition depending on the method being called. Review the JavaDoc to determine which of these classes contains the specific method you are calling.
> 4. replace references to oracle.portal.provider.v1.DefaultSecurityManager with oracle.portal.provider.v2.security.AuthLevelSecurityManager
> 5. change the type of variables storing providerId from long to java.lang.String . The datatype was changed to allow more flexibility in future releases of the API.

### Update Provider Definition Files (provider.xml):

> 1. replace references to oracle.portal.provider.v1.http.DefaultProvider with oracle.portal.provider.v2.DefaultProviderDefinition (or your own class that extends oracle.portal.provider.v2.ProviderDefinition)
> 2. replace references to oracle.portal.provider.v1.http.DefaultPortlet with oracle.portal.provider.v2.DefaultPortletDefinition (or your own class that extends oracle.portal.provider.v2.PortletDefinition)
> 3. replace references to oracle.portal.provider.v1.http.JspRenderer and oracle.portal.provider.v1.http.Servlet20Renderer with oracle.portal.provider.v2.render.http.ResourceRenderer.
> 4. replace JSP/Servlet file references with relative URIs based on the location of the resource (JSP/Servlet/file) within your provider’s WAR file. Review Packaging and Deploying Your Providers for a description of the provider WAR file and how it is used to deploy your provider.
> 5. replace references to oracle.portal.provider.v1.render.FileRenderer with oracle.portal.provider.v2.render.FileRenderer or oracle.portal.provider.v2.render.http.ResourceRenderer. ResourceRenderer can be used for JSPs, Servlets and static files. However, FileRenderer is recommended for static files because it can read files in any character set and after reading the file it caches it in memory, rendering subsequent requests from memory.
> 6. replace v1 personalization managers with the equivalent v2 personalization managers.

> > Version 2 of the PDK-Java framework includes two personalization managers:

> > - oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager
> > - oracle.portal.provider.v2.personalize.DBPersonalizationManager.

> > PrefStorePersonalizationManager replaces both FilePersonalizationManager and DBPersonalizationManager2, utilizing the new Preference Store functionality. To use the PrefStorePersonalizationManager, you must declare one or more preference stores in your provider definition file. The preference stores can be either file based or database-based. File or database preference stores are compatible with the the personalization managers included in PDK-Java 3.0.9

> > If you previously used:

> - FilePersonalizationManager, use PrefStorePersonalizationManager in conjunction with a file-based preference store
> - DBPersonalizationManager2 use PrefStorePersonalizationManager in conjunction with a database preference store
> - DBPersonalizationManager use the equivalent v2 DBPersonalizationManager

> > To declare a file based preference, use the following XML.

> > >     <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
> > >         <name>prefStore1</name>
> > >         <rootDirectory>d:\root\directory</rootDirectory>
> > >         <useHashing>true</useHashing>
> > >     </preferenceStore>

> > The <rootDirectory> should be the same as the <rootDirectory> you used with the FilePersonalizationManager . If you did not specify a root directory when you declared your FilePersonalizationManager, then <rootDirectory> should be the same as the provider_root argument passed to the provider servlet. If you want to move your personalization data to a new location, simply zip or tar up the contents of the original root directory (including all the subdirectories) and unzip or untar into the new location. The new value for <rootDirectory> will the the path of the directory into which the data was unzipped/untarred.

> > To declare a database-based preference store, use the following XML.

> > >     <preferenceStore class="oracle.portal.provider.v2.preference.DBPreferenceStore">
> > >         <name>prefStore2</name>
> > >         <connection>oc4jDataSourceName</connection>
> > >         <table>databaseTableName</table>
> > >     </preferenceStore>

> > If you are using the DBPreferenceStore, you must declare a datasource in the j2ee/home/config/datasources.xml of the OC4J instance in which your provider will be deployed. The DBPreferenceStore will use JNDI to locate the datasource it should use for the preference store. Preference stores must be declared inside the <provider> element at the same level as <portlet> elements.

### Provider Definition Files Before and After Upgrading

The Following section shows two provider definition files, the first from PDK-Java 3.0.9 and the second from PDK-Java 9.0.4. The highlighted areas show where there are differences between the 2 files.

Areas that are bold indicate that a value has changed. Most of these values are class names.

Areas that bold/italic indicate that the structure of the file has changed. The highlighted section may represent removal, addition or modification.

Sample Provider Definition File from PDK-Java 3.0.9

> <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

> <?providerDefinition version="2.0"?>
> <!DOCTYPE provider [
> <!ENTITY virtualRoot "/jpdk/">
> <!ENTITY physicalRoot "E:\9iAS\Apache\Apache\htdocs\jpdk\">
> ]>
> <provider class="oracle.portal.provider.v1.http.DefaultProvider ">
> <session>true</session>
> <containerRenderer class="oracle.portal.provider.v1.DefaultContainerRenderer " />
> <portlet class="oracle.portal.provider.v1.http.DefaultPortlet ">
> <id>1</id>
> <name>samplePortlet</name>
> <title>Sample Portlet</title>
> <shortTitle>Sample</shortTitle>
> <description>PDK-Java version 1 portlet definition</description>
> <timeout>10</timeout>
> <timeoutMessage>Sample Portlet timed out</timeoutMessage>
> <hasHelp>true</hasHelp>
> <hasAbout>true</hasAbout>
> <showDetails>true</showDetails>
> <showEdit>true</showEdit>
> <showEditDefault>true</showEditDefault>
> <acceptContentType>text/html</acceptContentType>
> <renderer class="oracle.portal.provider.v1.RenderManager ">
> <appPath>&virtualRoot;samplePortlet</appPath>
> <appRoot>&physicalRoot;samplePortlet</appRoot>
> <contentType>text/html</contentType>
> <showPage class="oracle.portal.provider.v1.http.JspRenderer">
> <name>showPage.jsp</name>
> </showPage>
> <helpPage class="oracle.portal.provider.v1.http.FileRenderer">
> <name>help.html</name>
> </helpPage>
> <editPage class="oracle.portal.provider.v1.http.Servlet20Renderer">
> <servletClass>your.package.EditServlet</servletClass>
> </editPage>
> <editDefaultsPage class="oracle.portal.provider.v1.http.Servlet20Renderer">
> <servletClass>your.package.EditServlet</servletClass>
> </editDefaultsPage>
> <aboutPage class="oracle.portal.provider.v1.http.FileRenderer">
> <name>about.html</name>
> </aboutPage>
> <showDetailsPage class="oracle.portal.provider.v1.http.JspRenderer">
> <name>details.jsp</name>
> </showDetailsPage>
> </renderer>
> <personalizationManager class=" oracle.portal.provider.v1.FilePersonalizationManager">
> <dataClass>your.package.DataClass</dataClass>
> <useHashing>true</useHashing>
> </personalizationManager>
> <securityManager class="oracle.portal.provider.v2.security.DefaultSecurityManager ">
> <authLevel>STRONG</authLevel>
> </securityManager>
> </portlet>
> </provider>

Sample Provider Definition File after following above steps

> <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
> <?providerDefinition version="3.1"?>
> <provider class="oracle.portal.provider.v2.DefaultProviderDefinition ">
> <session>false</session>
> <containerRenderer class="oracle.portal.provider.v2.render.DefaultContainerRenderer" />
> <preferenceStore class="oracle.portal.provider.v2.preference.FilePreferenceStore">
> <name>prefStore1</name>

> <rootDirectory>d:\root\directory</rootDirectory>
> <useHashing>true</useHashing>
> </preferenceStore>

> <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition ">
> <id>1</id>
> <name>samplePortlet</name>
> <title>Sample Portlet</title>
> <shortTitle>Sample</shortTitle>
> <description>PDK-Java version 2 portlet definition</description>
> <timeout>10</timeout>
> <timeoutMessage>Sample timed out</timeoutMessage>
> <hasHelp>true</hasHelp>
> <hasAbout>true</hasAbout>
> <showDetails>true</showDetails>
> <showEdit>true</showEdit>
> <showEditDefault>true</showEditDefault>
> <acceptContentType>text/html</acceptContentType>
> <renderer class="oracle.portal.provider.v2.render.RenderManager ">
> <contentType>text/html</contentType>
> <showPage class=" oracle.portal.provider.v2.render.ResourceRenderer">
> <resourcePath>/jsps/showPage.jsp</resourcePath>
> </showPage>
> <helpPage class="oracle.portal.provider.v2.render.http.FileRenderer">
> <appRoot>d:\this\is\the\file\path</appRoot>
> <name>help.html</name>
> </helpPage>
> <editPage>/servlet/editServlet</editPage>
> <editDefaultsPage>/servlet/editServlet</editDefaultsPage>
> <aboutPage>/htdocs/submitServlet/about.html</aboutPage>
> <showDetailsPage>/jsps/showDetails.jsp</showDetailsPage>
> </renderer>
> <personalizationManager class=" oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager " >
> <dataClass>your.package.DataClass</dataClass>
> </personalizationManager>
> <securityManager class="oracle.portal.provider.v2.security.AuthLevelSecurityManager ">
> <authLevel>STRONG</authLevel>
> </securityManager>
> </portlet>
> </provider>

### Package and Deploy Your Provider

The final step in the migration process is to package and deploy your provider. Please refer to Packaging and Deploying Your Providers for detailed instructions regarding packaging and deploying your provider on the OC4J platform.

Revision History: |
Revision No | Last Update | Description
1.0 | Augustl 24, 2001 | Created
1.1 | March 18, 2002 |
1.2 | August 16, 2003 | Revised branding and applied PDK Stylesheet
2.0 | November 5, 2003 | Added migration paths for PDK 9.0.4
2.1 | June 15, 2004 | Updated version number for PDK 90411 release
2.2 | August 27, 2004 | Updated version number for 1012 release
2.3 | May 22, 2006 | Updated version number for 1013 release
2.4 | February 7, 2007 | Updated version number for 10132 release

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/ | Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200 | Copyright and Corporate Info